Loops

Loops allow a BindAI workflow to repeat an operation or group of operations while a runtime decision indicates that another iteration should occur. Loops are useful when the same workflow logic must execute repeatedly, such as processing items, repeating validation, or continuing work until a condition is satisfied. BindAI V1 supports loop-based workflow execution as part of its workflow control-flow capabilities. The exact public API for defining workflow loops should be taken from the installed BindAI implementation.

What Is a Loop?

A loop creates repeated execution within a workflow. Conceptually:

Loop
  |
  v
Evaluate Decision
  |
  +-- Continue --> Loop Body
  |                  |
  |                  +----> Loop
  |
  +-- Stop -------> Exit

The loop determines whether another iteration should execute. After the loop body completes, execution can return to the loop decision.

Why Use Loops?

Loops are useful when workflow logic must execute repeatedly. Common examples include:

Processing collections
Processing batches
Repeated validation
Iterative analysis
Processing paginated data
Incremental synchronization
Repeating an operation until a desired state is reached

Without loop behavior, repeated workflow logic would need to be duplicated or manually represented through graph structure.

Loop Execution Flow

A typical loop follows this pattern:

Evaluate Decision
      |
  +---+---+
  |       |
Continue  Stop
  |       |
  v       v
Body     Exit
  |
  v
Update State
  |
  +------> Evaluate Decision

When the continuation decision is true, the workflow executes the loop body. After the body completes, the workflow evaluates the decision again. When the decision becomes false, execution leaves the loop.

Loop State

Loops normally depend on information that changes as execution progresses. For example:

Initialize State
       |
       v
Evaluate Loop
       |
       v
Process Item
       |
       v
Update State
       |
       +----> Evaluate Loop

The loop body should make progress toward its terminating state. If the state used by the loop decision never changes, the workflow may continue indefinitely.

Loop Body

The loop body contains the operations performed during one iteration. For example:

Loop
  |
  v
Agent
  |
  v
Tool
  |
  v
Update State
  |
  +----> Loop

A loop body can contain multiple workflow operations, including:

Agents
Tools
Conditions
Application processing
Validation
Connection-backed tools

The body should remain focused on the work required for one iteration.

Loop Decisions

The continuation decision determines whether another iteration should occur. Conceptually:

Current Workflow State
        |
        v
Continuation Decision
     /         \
   True        False
    |            |
    v            v
  Body          Exit

The decision can depend on values produced during workflow execution. For example, a workflow may continue while:

More items remain
A task is incomplete
A validation condition is not satisfied
Additional pages are available
Additional work remains

The exact decision expression and configuration should follow the implemented BindAI workflow API.

Example: Processing a Collection

A common loop pattern processes items one at a time.

Initialize Items
      |
      v
    Loop
      |
      v
Process Current Item
      |
      v
Advance Position
      |
      +------> Loop

Conceptually, the workflow may maintain:

items
position

The continuation decision checks whether another item remains. For example:

position < number_of_items

The loop body processes the current item and advances the workflow state.

Example: Batch Processing

Loops can process batches incrementally.

Load Batch
    |
    v
  Loop
    |
    v
Process Batch
    |
    v
Load Next Batch
    |
    +------> Loop

The continuation decision determines whether another batch remains. This can keep each iteration focused on a manageable unit of work.

Example: Pagination

A workflow can repeatedly process pages of data.

Request Page
     |
     v
Process Results
     |
     v
More Pages?
   /       \
 Yes        No
  |          |
  v          v
Next Page   Exit
  |
  +----> Process Results

The workflow can use pagination information returned by an operation to determine whether another iteration is required.

Example: Repeated Validation

A workflow may repeat processing until a desired state is reached.

Prepare Data
     |
     v
Validate
     |
     v
Valid?
 /     \
Yes     No
 |       |
 v       v
Exit   Update Data
          |
          +----> Validate

The workflow should have a reliable termination mechanism when the state being evaluated is unpredictable.

Loops with Conditions

Conditions can participate inside a loop.

Loop
  |
  v
Agent
  |
  v
Condition
 /       \
Continue  Stop
  |        |
  v        v
Update    Exit
State
  |
  +----> Loop

The loop controls repetition. The condition controls a decision within the iteration. This is useful when each iteration can have multiple outcomes.

Loops with Agents

An Agent node can participate in each loop iteration. For example:

Loop
  |
  v
Agent
  |
  v
Evaluate Result
  |
  v
Update State
  |
  +----> Loop

This can be useful for:

Iterative analysis
Classification of multiple items
Repeated planning
Processing a collection of requests

The workflow should still provide a clear termination mechanism independently of the model’s output.

Loops with Tools

Tool nodes are useful when each iteration performs deterministic work.

Loop
  |
  v
Tool
  |
  v
Tool Result
  |
  v
Update State
  |
  +----> Loop

Examples include:

Processing records
Calling an API for each item
Performing calculations
Writing application data
Synchronizing external resources

Tool execution remains responsible for the operation itself, while the workflow controls iteration.

Loops with Connection-Backed Tools

A loop can repeatedly execute a connection-backed tool. For example:

Loop
  |
  v
Webhook Tool
  |
  v
Result
  |
  v
Update State
  |
  +----> Loop

This can be useful when an application needs to perform the same external operation for multiple workflow items. In BindAI V1, Webhook is the implemented Studio connection provider.

Loops with Knowledge

An Agent node inside a loop can use configured Knowledge during each iteration. For example:

Loop
  |
  v
Agent
  |
  +--> Knowledge
  |
  v
Process Result
  |
  +----> Loop

This can be useful when each item requires separate contextual analysis. Knowledge remains responsible for providing searchable information, while the workflow controls iteration.

Loops with Memory

An Agent node inside a loop can also use configured Memory. For example:

Loop
  |
  v
Agent
  |
  +--> Memory
  |
  v
Update Workflow State
  |
  +----> Loop

Memory can preserve information for agent interactions. Workflow state, meanwhile, carries information required by the current workflow execution.

Nested Loops

Loops can conceptually be combined with other loops. For example:

Outer Loop
    |
    v
Inner Loop
    |
    v
Process
    |
    +----> Inner Loop

A common example is hierarchical data:

For each customer
    |
    +--> For each order
             |
             +--> Process Order

Nested loops can be useful, but excessive nesting can make workflows difficult to understand and debug.

Avoiding Unbounded Loops

Every loop should have a reliable path toward termination. For example:

Counter
  |
  v
Evaluate
  |
  v
counter < limit
  |
  v
Process
  |
  v
Advance Counter
  |
  +----> Evaluate

Eventually:

counter >= limit
      |
      v
    Exit

The important property is that the loop body changes the state used by the continuation decision.

Loop Progress

A useful loop should make measurable progress. For example:

Iteration 1
   |
   v
Process Item 1
   |
   v
Iteration 2
   |
   v
Process Item 2
   |
   v
Iteration 3

Progress can be represented by:

An item position
A page number
A batch identifier
A completion flag
Remaining work
Application state

Making progress explicit helps prevent accidental non-termination.

Loop State and Workflow Variables

Loop state can be stored in workflow variables. For example:

items
current_index
processed_count

A typical flow is:

Workflow Variables
       |
       v
Loop Decision
       |
       v
Loop Body
       |
       v
Updated Variables
       |
       +----> Loop Decision

The variables required by the loop should be initialized before the loop begins.

Loop Exit

Every loop should have a clear exit path.

Loop Decision
   |
   +-- Continue --> Body --> Loop
   |
   +-- Stop -----> Exit

The exit path allows downstream workflow operations to continue after iteration is complete. A loop without a reachable exit can cause unbounded workflow execution.

Loop and Retry Are Different

Loops and retries both involve repeated execution, but they represent different concepts.

Loop	Retry
Repeats intentional workflow logic	Repeats failed execution
Part of normal workflow control flow	Reliability mechanism
Usually controlled by workflow state	Triggered by failure
Can process many iterations	Usually concerned with attempts
Represents business or processing logic	Handles execution failure

Use a loop when repetition is part of the intended workflow behavior. Retry is a separate capability and is outside the verified advanced V1 workflow scope.

Error Handling Inside Loops

A failure inside a loop body can affect the workflow execution. For example:

Loop Body
    |
    v
Operation
    |
    +--> Success --> Update State --> Loop
    |
    +--> Failure --> Workflow Error

The application should define appropriate failure behavior for important loop operations. For V1, do not assume that every loop automatically retries failed operations.

Testing Loops

Loop behavior should be tested across several scenarios.

Zero iterations

The continuation decision is initially false.

Loop
  |
  v
False
  |
  v
Exit

The loop body should not execute.

One iteration

The decision is initially true but becomes false after one iteration.

Loop
  |
  v
True
  |
  v
Body
  |
  v
Loop
  |
  v
False
  |
  v
Exit

Multiple iterations

The decision remains true for several iterations before becoming false.

Loop
  |
  v
Body
  |
  v
Body
  |
  v
Body
  |
  v
Exit

Non-terminating state

The continuation decision never becomes false. This should be treated as an invalid workflow design or execution condition that requires an appropriate application-level safeguard.

Testing Loop State

Tests should verify that workflow state changes as expected. For example:

Initial:
current_index = 0

Iteration 1:
current_index = 1

Iteration 2:
current_index = 2

Iteration 3:
current_index = 3

Exit:
current_index = 3

This verifies both the loop body and its termination condition.

Loop Design Pattern

A reliable loop generally follows this pattern:

Initialize State
      |
      v
Loop Decision
   /       \
 Stop     Continue
  |          |
  v          v
Exit      Execute Body
             |
             v
         Update State
             |
             +----> Loop Decision

The important property is that the body changes the state used by the continuation decision. That creates measurable progress toward termination.

Common Use Cases

Loop behavior is useful for:

Collection processing
Batch processing
Pagination
Iterative validation
Incremental synchronization
Repeated agent processing
Repeated tool operations
Processing remaining work
Iterative application workflows

Best Practices

When designing loops:

Define a clear termination condition.
Make sure the loop can eventually exit.
Update the state used by the continuation decision.
Keep the loop body focused.
Avoid unnecessary nested loops.
Make progress explicit.
Keep loop conditions readable.
Test zero, one, multiple, and terminating iterations.
Test the workflow state after each iteration where appropriate.
Avoid depending on model output alone for termination.
Keep external operations inside tools or connection-backed tools.
Define failure behavior for important loop operations.

Current BindAI V1 Scope

BindAI V1 supports loop-based workflow orchestration. Loops can currently be combined with:

Agent nodes
Tool nodes
Condition nodes
Connection-backed tools
Workflow variables
Workflow state
Memory-enabled agents
Knowledge-enabled agents
Parallel and Join workflow structures
Human Tasks

Loops provide the workflow control-flow mechanism for repeated execution.

Deferred Features

The following are outside the verified V1 loop feature set:

Advanced retry policies
Advanced timeout policies
Workflow scheduling
Automation triggers
Distributed loop execution
Advanced loop monitoring
Advanced cancellation APIs
Advanced loop administration

These should only be documented as implemented features after they are actually available and verified.

API Accuracy

This documentation intentionally does not assume specific public APIs such as:

builder.loop(...)
LoopNode(...)
WorkflowLoop(...)

or a particular predicate signature unless those APIs are verified in the current BindAI implementation. The verified V1 capability is loop-based workflow execution through the workflow runtime and Studio workflow configuration. When a concrete public loop API is exposed, documentation should include:

The actual import path.
The actual constructor or factory.
The actual parameters.
The loop decision behavior.
The loop-body behavior.
The exit behavior.
Tests demonstrating the behavior.

Summary

Loops allow BindAI workflows to repeat intentional workflow logic. A typical loop follows:

Decision
   |
   +-- Continue → Body → Update State → Decision
   |
   +-- Stop ----> Exit

Loops are useful for collections, batches, pagination, iterative validation, repeated agent processing, repeated tool execution, and other intentional repeated operations. The most important loop requirement is a clear path toward termination.

Loops repeat intentional workflow behavior; the loop body should make measurable progress toward its exit condition.

Specific loop APIs should only be documented after they are verified against the current BindAI implementation and tests.

​Loops

​What Is a Loop?

​Why Use Loops?

​Loop Execution Flow

​Loop State

​Loop Body

​Loop Decisions

​Example: Processing a Collection

​Example: Batch Processing

​Example: Pagination

​Example: Repeated Validation

​Loops with Conditions

​Loops with Agents

​Loops with Tools

​Loops with Connection-Backed Tools

​Loops with Knowledge

​Loops with Memory

​Nested Loops

​Avoiding Unbounded Loops

​Loop Progress

​Loop State and Workflow Variables

​Loop Exit

​Loop and Retry Are Different

​Error Handling Inside Loops

​Testing Loops

​Zero iterations

​One iteration

​Multiple iterations

​Non-terminating state

​Testing Loop State

​Loop Design Pattern

​Common Use Cases

​Best Practices

​Current BindAI V1 Scope

​Deferred Features

​API Accuracy

​Summary